.Dd September 21, 2025
.Dt R_HASH 3
.Os
.Sh NAME
.Nm r_hash
.Nd Hashing and checksum library for radare2
.Sh SYNOPSIS
.In r_hash.h
.Ft RHash *
.Fn r_hash_new "bool rst" "ut64 flags"
.Ft void
.Fn r_hash_free "RHash *ctx"
.Pp
The following are representative function prototypes used throughout the library and examples in this manual page; more prototypes are provided in the header.
.Sh DESCRIPTION
The
.Nm r_hash
library implements many common hashing and checksum primitives (MD4/MD5/SHA family, CRCs, Adler, SipHash, xxHash, ssdeep, etc.), plus analysis helpers such as entropy and hamming distance.
.Pp
The main structure is
.Vt struct r_hash_t ,
which stores intermediate contexts for several algorithms and an aligned digest buffer.
.Sh INITIALIZATION
Initialization and cleanup functions handle allocation and freeing of a hash context. The `rst` argument controls whether the context is reset between operations and `flags` selects which algorithms to prepare.
.Ft RHash *
.Fn r_hash_new "bool rst" "ut64 flags"
.Ft void
.Fn r_hash_free "RHash *ctx"
.Pp
Typical usage in applications: create a context once with the algorithms you need (for example `R_HASH_MD5 | R_HASH_SHA256`) and reuse it for multiple inputs to avoid repeated allocations, calling `r_hash_free` when done.
.Sh CORE OPERATIONS
Core single-shot and multi-algorithm operations compute digests and expose helpers to map names and sizes.
.Ft ut8 *
.Fn r_hash_do_md5 "RHash *ctx" "const ut8 *input" "int len"
.Ft ut8 *
.Fn r_hash_do_sha1 "RHash *ctx" "const ut8 *input" "int len"
.Ft ut8 *
.Fn r_hash_do_sha256 "RHash *ctx" "const ut8 *input" "int len"
.Ft int
.Fn r_hash_calculate "RHash *ctx" "ut64 algobit" "const ut8 *input" "int len"
.Ft const char *
.Fn r_hash_name "ut64 bit"
.Ft int
.Fn r_hash_size "ut64 bit"
.Ft char *
.Fn r_hash_tostring "RHash *ctx" "const char *name" "const ut8 *data" "int len"
.Pp
Use `r_hash_calculate` when you want to compute several algorithms into the context's `digest` buffer at once; it returns the digest size in bytes for the requested algorithm bit. Use `r_hash_name` and `r_hash_size` to print properly sized hex dumps.
.Sh CHECKSUMS AND ANALYSIS
The library provides many lightweight checksum and analysis helpers useful when scanning binary buffers or computing features for heuristics (entropy, parity, xor, Adler32, xxhash, ssdeep fingerprinting, etc.).
.Ft ut32
.Fn r_hash_adler32 "const ut8 *buf" "int len"
.Ft ut32
.Fn r_hash_xxhash "const ut8 *buf" "ut64 len"
.Ft ut8
.Fn r_hash_xor "const ut8 *b" "ut64 len"
.Ft double
.Fn r_hash_entropy "const ut8 *data" "ut64 len"
.Ft char *
.Fn r_hash_ssdeep "const ut8 *buf" "size_t len"
.Pp
In radare2, these helpers are used for file heuristics (for example computing entropy to detect packed or compressed regions) and for concise diagnostics (e.g., showing a `ssdeep` fuzzy hash for similarity). `r_hash_entropy_fraction` returns a normalized value [0..1] used by UI code.
.Sh ADVANCED / INCREMENTAL USAGE
For streaming or incremental hashing (hashing a large file chunk-by-chunk), the library exposes begin/end primitives and `r_hash_do_spice` for repeated re-hashing with a seed (used by `rahash2` to perform iterative strengthening).
.Ft void
.Fn r_hash_do_begin "RHash *ctx" "ut64 flags"
.Ft void
.Fn r_hash_do_end "RHash *ctx" "ut64 flags"
.Ft void
.Fn r_hash_do_spice "RHash *ctx" "ut64 algo" "int loops" "RHashSeed *seed"
.Ft ut8 *
.Fn r_hash_do_hmac_sha256 "RHash *ctx" "const ut8 *input" "int len" "const ut8 *key" "int klen"
.Pp
A common pattern (see `rahash2` and `r_hash` usage in `libr/main/rahash2.c`) is:
.Bd -literal -offset indent
r_hash_do_begin (ctx, R_HASH_SHA256);
// feed chunks with r_hash_calculate or algorithm-specific functions
r_hash_calculate (ctx, R_HASH_SHA256, chunk, chunk_len);
r_hash_do_end (ctx, R_HASH_SHA256);
// result is in ctx->digest
.Ed
.Pp
When you need to perform key-based MACs, use `r_hash_do_hmac_sha256` to obtain the HMAC-SHA256 digest in a single call.
.Sh PRACTICAL EXAMPLES
The examples below show real-life usage patterns found in `libr/main/rahash2.c`, `libr/core/cbin.c` and `libr/core/cmd_print.inc.c`.
.Pp
Example: compute chunked hashes of a file (adapted from `rahash2`):
.Bd -literal -offset indent
// open file and create ctx with the chosen algorithm bit
RHash *ctx = r_hash_new (true, R_HASH_SHA256);
// incremental mode: begin, feed chunks, end
r_hash_do_begin (ctx, R_HASH_SHA256);
for (offset = 0; offset < file_size; offset += block_size) {
    int len = MIN (block_size, file_size - offset);
    r_io_pread_at (io, offset, buf, len); // read into buf
    r_hash_calculate (ctx, R_HASH_SHA256, buf, len);
}
r_hash_do_end (ctx, R_HASH_SHA256);
// ctx->digest contains the SHA-256 result (32 bytes)
char *s = r_hash_tostring (ctx, "sha256", ctx->digest, 32);
printf ("sha256: %s\n", s);
free (s);
r_hash_free (ctx);
.Ed
.Pp
Example: compute entropy and display as a 0..255 value (used by `cmd_print`):
.Bd -literal -offset indent
double ent = r_hash_entropy_fraction (data, data_size);
ut8 visual = (ut8)(ent * 255);
printf ("entropy_frac=%.3f, visual=%u\n", ent, visual);
.Ed
.Pp
Example: compare a computed digest against an expected one (pattern from `rahash2`):
.Bd -literal -offset indent
RHash *ctx = r_hash_new (true, R_HASH_MD5);
r_hash_calculate (ctx, R_HASH_MD5, buf, len);
if (!memcmp (ctx->digest, expected_digest, 16)) {
    puts ("match");
} else {
    puts ("mismatch");
}
r_hash_free (ctx);
.Ed
.Pp
Example: produce a `ssdeep` fuzzy hash string for a buffer:
.Bd -literal -offset indent
char *fuzzy = r_hash_ssdeep (buf, len);
if (fuzzy) {
    printf ("ssdeep: %s\n", fuzzy);
    free (fuzzy);
}
.Ed
.Sh NOTES
Function names and bitmasks are declared in `libr/include/r_hash.h`. Pick the exact algorithm using `r_hash_name_to_bits`/`r_hash_name` helpers when mapping user strings to bit flags.
.Pp
Many radare2 internal users create a single `RHash` and call `r_hash_calculate` repeatedly; prefer incremental `do_begin`/`do_end` when hashing very large streams to avoid copying large buffers into memory.
.Sh SEE ALSO
.Xr r_bin 3 ,
.Xr r_core 3 ,
.Xr r_util 3
